Readme #462

devcrocod · 2025-12-11T22:47:02Z

#162

Motivation and Context

update readme
add more snippets
add knit

How Has This Been Tested?

knit

Breaking Changes

None

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Copilot

Pull request overview

This PR significantly enhances the Kotlin MCP SDK documentation by expanding the README with comprehensive usage examples, adding detailed module documentation, and integrating the Knit tool for validating code snippets. The update transforms minimal documentation into a complete developer guide with quickstart examples, core concepts, and feature demonstrations.

Expanded README from basic overview to comprehensive guide with installation instructions, quickstart examples, and detailed feature documentation
Added extensive module documentation (Module.md) for core, client, and server packages with code examples
Integrated Knit build tool for automated code snippet validation

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
settings.gradle.kts	Added `:docs` module to the build
gradle/libs.versions.toml	Added knit plugin version 0.5.0 and fixed junit formatting
docs/build.gradle.kts	Created build configuration for docs module with knit plugin setup
docs/.gitignore	Added gitignore to exclude knit-generated sources
knit.properties	Created knit configuration for code snippet extraction
README.md	Completely rewrote with table of contents, comprehensive examples, core concepts, transports, and API documentation
kotlin-sdk-core/Module.md	Expanded from minimal overview to detailed module documentation with usage examples
kotlin-sdk-client/Module.md	Expanded with comprehensive client setup examples and feature descriptions
kotlin-sdk-server/Module.md	Expanded with server setup examples, feature registration details, and lifecycle information
docs/moduledoc.md	Streamlined and updated module overview with clearer structure and updated code examples
.github/workflows/build.yml	Added knit validation step to the CI build workflow

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

README.md

Copilot · 2025-12-11T22:50:13Z

README.md

+
+<!--- KNIT example-server-util-pagination-01.kt -->
+
+Include `nextCursor` only when more items remain an absent cursor ends pagination.


There's a missing punctuation mark between "remain" and "an". The sentence should either use a period, semicolon, or conjunction. Consider: "Include nextCursor only when more items remain. An absent cursor ends pagination." or "Include nextCursor only when more items remain; an absent cursor ends pagination."

Suggested change

Include `nextCursor` only when more items remain an absent cursor ends pagination.

Include `nextCursor` only when more items remain. An absent cursor ends pagination.

kpavlov

Thank you, @devcrocod

I’ve noticed that Knit isn’t being applied to MD files, even though it’s been added. Let’s consider enabling it in the next PRs.

Also, would it be a good idea to move the examples from _Module.md_s to the main README.md? That way, it’ll be easier for people and AI agents to find them. What do you think?

kpavlov · 2025-12-12T10:51:10Z

docs/moduledoc.md

-A minimal client:
+Minimal WebSocket client:

 ```kotlin


let's enable knit for this example

kpavlov · 2025-12-12T10:51:25Z

docs/moduledoc.md

-    // Build and return a CallToolResult from request.arguments
-    // (see CallToolResult and related types in kotlin-sdk-core)
-    /* ... */
+fun Application.module() {


let's enable knit for this example

kpavlov · 2025-12-12T10:52:33Z

kotlin-sdk-client/Module.md

+
+### Minimal STDIO client
+
+```kotlin


let's add knit for the example too

kpavlov · 2025-12-12T10:54:03Z

kotlin-sdk-server/Module.md

+
+### Minimal STDIO server
+
+```kotlin


let's add knit

kpavlov · 2025-12-12T10:54:10Z

kotlin-sdk-server/Module.md

+
+### Hosting with Ktor (SSE)
+
+```kotlin


devcrocod · 2025-12-12T14:24:34Z

@kpavlov

I’ve noticed that Knit isn’t being applied to MD files, even though it’s been added. Let’s consider enabling it in the next PRs.

In this PR, I added knit only for the Readme.md file for now.

I haven’t set it up for the module.md files yet. We can add that later. For now, I only updated those files because they were outdated

Also, would it be a good idea to move the examples from _Module.md_s to the main README.md? That way, it’ll be easier for people and AI agents to find them. What do you think?

For now, I prefer not to do this
it would overload the README and complicate it. These files are used by dokka, and since they are in the repository, they are also easily accessible to AI agents. I’m currently exploring ways to integrate dokka into writerside, so they may eventually become part of the user documentation

kpavlov · 2025-12-12T19:05:58Z

I don't agree, that Readme would get too crowded. It’s pretty standard these days to have a one-page manual, and that’s what I’m getting at.

You could use the

Details

tag in HTML to hide the examples, which would make it look nicer for people, but still give AI/crawlers all the info they need.

…nippets

…ns, and knit snippets

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 13 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-28T17:43:44Z

kotlin-sdk-core/Module.md

@@ -1,5 +1,47 @@
-# Module kotlin-sdk-core
+# kotlin-sdk-core


Module.md files are included into Dokka via buildSrc/src/main/kotlin/mcp.dokka.gradle.kts:10 (includes.from("Module.md")). Dokka’s module documentation format expects the header to start with # Module <module-name>; changing this to # kotlin-sdk-core may prevent the content from being recognized as module docs. Consider restoring the # Module kotlin-sdk-core heading.

Suggested change

# kotlin-sdk-core

# Module kotlin-sdk-core

Copilot · 2026-01-28T17:43:44Z

kotlin-sdk-client/Module.md

+1. Declare client capabilities with `ClientOptions` (e.g., tools, prompts, resources, logging, roots, sampling,
+   elicitation).


ClientCapabilities in this repo only models client-advertised capabilities (sampling, roots, elicitation, experimental). Mentioning tools/prompts/resources/logging here is misleading because those are server capabilities, and it suggests configuration options that don’t exist on ClientCapabilities. Update the wording to reflect the actual fields.

Copilot · 2026-01-28T17:43:44Z

kotlin-sdk-client/Module.md

+    clientOptions = ClientOptions(
+        capabilities = ClientCapabilities(
+            tools = ClientCapabilities.Tools(),
+            resources = ClientCapabilities.Resources(subscribe = true),
+        )
+    ),


This example won’t compile: ClientCapabilities has no Tools/Resources nested types nor tools/resources properties (see kotlin-sdk-core/src/commonMain/.../capabilities.kt). Use ClientOptions() (default) or set only supported fields like roots/sampling/elicitation.

Suggested change

clientOptions = ClientOptions(

capabilities = ClientCapabilities(

tools = ClientCapabilities.Tools(),

resources = ClientCapabilities.Resources(subscribe = true),

)

),

clientOptions = ClientOptions(),

Copilot · 2026-01-28T17:43:45Z

kotlin-sdk-client/Module.md

+- **SSE** (streaming GET + POST back-channel): create `SSEClientTransport(baseUrl, httpClient)`; sessions are keyed by
+  `sessionId` managed by the SDK.
+- **WebSocket**: use `WebSocketClientTransport(url, httpClient)` to get bidirectional messaging in one connection.
+- **Streamable HTTP**: `StreamableHttpClientTransport` enables MCP over streaming HTTP where WebSockets are unavailable.


The transport constructor examples here don’t match the actual APIs:

SSEClientTransport is a typealias deprecated with DeprecationLevel.ERROR in favor of SseClientTransport.

SseClientTransport/WebSocketClientTransport constructors take (httpClient, url) (or prefer HttpClient.mcpSseTransport(...) / HttpClient.mcpWebSocketTransport(...)).
Update these backticked call patterns so they’re copy/paste correct.

Copilot · 2026-01-28T17:43:45Z

kotlin-sdk-server/Module.md

+val server = Server(
+    serverInfo = Implementation(name = "demo-server", version = "1.0.0"),
+    options = ServerOptions(
+        capabilities = ServerCapabilities(
+            tools = ServerCapabilities.Tools(listChanged = true)
+        )
+    )
+) {
+    addTool(
+        name = "hello",
+        description = "Greets the caller by name"
+    ) { request ->
+        val name = request.params.arguments["name"]?.jsonPrimitive?.content ?: "there"
+        CallToolResult(
+            content = listOf(TextContent("Hello, $name!")),
+            isError = false,
+        )
+    }
+}
+
+val transport = StdioServerTransport(System.`in`.source(), System.out.sink())
+server.createSession(transport)


This snippet uses APIs that don’t exist / won’t compile as written:

System.in.source() / System.out.sink() should be asSource()/asSink() (kotlinx-io).

Server.createSession(...) is suspend, so calling it at top-level (outside a suspend fun main/runBlocking) isn’t valid Kotlin.
Consider updating the example to a suspend fun main (or runBlocking) and use the correct stdio adapters.

Suggested change

val server = Server(

serverInfo = Implementation(name = "demo-server", version = "1.0.0"),

options = ServerOptions(

capabilities = ServerCapabilities(

tools = ServerCapabilities.Tools(listChanged = true)

)

)

) {

addTool(

name = "hello",

description = "Greets the caller by name"

) { request ->

val name = request.params.arguments["name"]?.jsonPrimitive?.content ?: "there"

CallToolResult(

content = listOf(TextContent("Hello, $name!")),

isError = false,

)

}

}

val transport = StdioServerTransport(System.`in`.source(), System.out.sink())

server.createSession(transport)

import kotlinx.io.asSink

import kotlinx.io.asSource

suspend fun main() {

val server = Server(

serverInfo = Implementation(name = "demo-server", version = "1.0.0"),

options = ServerOptions(

capabilities = ServerCapabilities(

tools = ServerCapabilities.Tools(listChanged = true)

)

)

) {

addTool(

name = "hello",

description = "Greets the caller by name"

) { request ->

val name = request.params.arguments["name"]?.jsonPrimitive?.content ?: "there"

CallToolResult(

content = listOf(TextContent("Hello, $name!")),

isError = false,

)

}

}

val transport = StdioServerTransport(System.`in`.asSource(), System.out.asSink())

server.createSession(transport)

}

Copilot · 2026-01-28T17:43:46Z

kotlin-sdk-client/Module.md

@@ -1,10 +1,74 @@
-# Module kotlin-sdk-client
+# kotlin-sdk-client


Module.md files are included into Dokka via buildSrc/src/main/kotlin/mcp.dokka.gradle.kts:10 (includes.from("Module.md")). Dokka’s module documentation format expects the header to start with # Module <module-name>; changing this to # kotlin-sdk-client may prevent the content from being recognized as module docs. Consider restoring the # Module kotlin-sdk-client heading.

Suggested change

# kotlin-sdk-client

# Module kotlin-sdk-client

Copilot · 2026-01-28T17:43:46Z

kotlin-sdk-client/Module.md

+            resources = ClientCapabilities.Resources(subscribe = true),
+        )
+    ),
+    transport = StdioClientTransport(System.`in`.source(), System.out.sink())


System.in.source() / System.out.sink() aren’t APIs provided by this codebase’s stdio transports (they use kotlinx.io.asSource()/asSink() + buffered()). As written, the snippet won’t compile for readers. Update the example to use the kotlinx.io adapters consistent with the SDK’s own docs/tests.

Copilot · 2026-01-28T17:43:47Z

kotlin-sdk-server/Module.md

@@ -1,14 +1,122 @@
-# Module kotlin-sdk-server
+# kotlin-sdk-server


Module.md files are included into Dokka via buildSrc/src/main/kotlin/mcp.dokka.gradle.kts:10 (includes.from("Module.md")). Dokka’s module documentation format expects the header to start with # Module <module-name>; changing this to # kotlin-sdk-server may prevent the content from being recognized as module docs. Consider restoring the # Module kotlin-sdk-server heading.

Suggested change

# kotlin-sdk-server

# Module kotlin-sdk-server

Copilot · 2026-01-28T17:43:47Z

kotlin-sdk-server/Module.md

+        name = "hello",
+        description = "Greets the caller by name"
+    ) { request ->
+        val name = request.params.arguments["name"]?.jsonPrimitive?.content ?: "there"


CallToolRequestParams.arguments is nullable (JsonObject?). Indexing directly (request.params.arguments["name"]) won’t compile. Use request.arguments?.get("name") (or request.params.arguments?.get("name")) before accessing jsonPrimitive.

Suggested change

val name = request.params.arguments["name"]?.jsonPrimitive?.content ?: "there"

val name = request.params.arguments?.get("name")?.jsonPrimitive?.content ?: "there"

Copilot · 2026-01-28T17:43:47Z

docs/moduledoc.md

+val client = mcpClient(
+    clientInfo = Implementation("sample-client", "1.0.0"),
+    clientOptions = ClientOptions(ClientCapabilities(tools = ClientCapabilities.Tools())),
+    transport = WebSocketClientTransport("ws://localhost:8080/mcp")


This WebSocket client example won’t compile:

ClientCapabilities has no tools/Tools (client capabilities are sampling/roots/elicitation/experimental).

WebSocketClientTransport requires an HttpClient argument (or use HttpClient.mcpWebSocketTransport(url)), not just a URL string.
Update the snippet to match the actual constructors/types.

Suggested change

val client = mcpClient(

clientInfo = Implementation("sample-client", "1.0.0"),

clientOptions = ClientOptions(ClientCapabilities(tools = ClientCapabilities.Tools())),

transport = WebSocketClientTransport("ws://localhost:8080/mcp")

val httpClient = HttpClient()

val client = mcpClient(

clientInfo = Implementation("sample-client", "1.0.0"),

clientOptions = ClientOptions(ClientCapabilities()),

transport = WebSocketClientTransport(httpClient, "ws://localhost:8080/mcp"),

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

devcrocod requested review from Ololoshechkin, Copilot, kpavlov and tiginamaria December 11, 2025 22:47

Copilot started reviewing on behalf of devcrocod December 11, 2025 22:47 View session

Copilot AI reviewed Dec 11, 2025

View reviewed changes

kpavlov previously approved these changes Dec 12, 2025

View reviewed changes

kpavlov dismissed their stale review via 4f9927c January 9, 2026 21:49

devcrocod added 4 commits January 28, 2026 18:28

Update Readme and add knit

fcd0d41

Update README with expanded sections and knit examples

e94033f

Expand README with detailed examples, structured sections, and knit s…

50c8a4c

…nippets

Expand module documentation with detailed examples, structured sectio…

da90e1b

…ns, and knit snippets

Copilot AI review requested due to automatic review settings January 28, 2026 17:28

devcrocod force-pushed the devcrocod/readme branch from 4f9927c to da90e1b Compare January 28, 2026 17:28

Copilot started reviewing on behalf of devcrocod January 28, 2026 17:29 View session

Copilot AI reviewed Jan 28, 2026

View reviewed changes

devcrocod added 2 commits January 28, 2026 18:58

Standardize module headers across documentation files

d6c6df3

Add knit workflow for generating and verifying code snippets in docs

418b8e7

Copilot AI review requested due to automatic review settings January 28, 2026 18:23

Copilot started reviewing on behalf of devcrocod January 28, 2026 18:23 View session

Copilot AI reviewed Jan 28, 2026

View reviewed changes


		<!--- KNIT example-server-util-pagination-01.kt -->

		Include `nextCursor` only when more items remain an absent cursor ends pagination.

		1. Declare client capabilities with `ClientOptions` (e.g., tools, prompts, resources, logging, roots, sampling,
		elicitation).

		@@ -1,10 +1,74 @@
		# Module kotlin-sdk-client
		# kotlin-sdk-client

		@@ -1,14 +1,122 @@
		# Module kotlin-sdk-server
		# kotlin-sdk-server

	val name = request.params.arguments["name"]?.jsonPrimitive?.content ?: "there"
	val name = request.params.arguments?.get("name")?.jsonPrimitive?.content ?: "there"

Readme #462

Are you sure you want to change the base?

Readme #462

Conversation

devcrocod commented Dec 11, 2025

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

kpavlov left a comment

Choose a reason for hiding this comment

Uh oh!

kpavlov Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

kpavlov Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

kpavlov Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

kpavlov Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

kpavlov Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

devcrocod commented Dec 12, 2025

Uh oh!

kpavlov commented Dec 12, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!